\documentclass[]{article}
\usepackage{lmodern}
\usepackage{amssymb,amsmath}
\usepackage{ifxetex,ifluatex}
\usepackage{fixltx2e} % provides \textsubscript
\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
\else % if luatex or xelatex
  \ifxetex
    \usepackage{mathspec}
    \usepackage{xltxtra,xunicode}
  \else
    \usepackage{fontspec}
  \fi
  \defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase}
  \newcommand{\euro}{€}
\fi
% use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
% use microtype if available
\IfFileExists{microtype.sty}{%
\usepackage{microtype}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\ifxetex
  \usepackage[setpagesize=false, % page size defined by xetex
              unicode=false, % unicode breaks when used with xetex
              xetex]{hyperref}
\else
  \usepackage[unicode=true]{hyperref}
\fi
\hypersetup{breaklinks=true,
            bookmarks=true,
            pdfauthor={},
            pdftitle={Figaro Guide},
            colorlinks=true,
            citecolor=blue,
            urlcolor=blue,
            linkcolor=magenta,
            pdfborder={0 0 0}}
\urlstyle{same}  % don't use monospace font for urls
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
\setlength{\emergencystretch}{3em}  % prevent overfull lines
\setcounter{secnumdepth}{0}

\title{Figaro Guide}
\date{}

\begin{document}
\maketitle

\subsection{About Figaro}\label{about-figaro}

Reasoning under uncertainty requires taking what you know and inferring
what you don't know, when what you know doesn't tell you for sure what
you don't know. A well-established approach for reasoning under
uncertainty is probabilistic reasoning. Typically, you create a
probabilistic model over all the variables you're interested in, observe
the values of some variables, and query others. There is a huge variety
of probabilistic models, and new ones are being developed constantly.
Figaro is designed to help build and reason with the wide range of
probabilistic models.

Developing a new probabilistic model normally requires developing a
representation for the model and a reasoning algorithm that can draw
useful conclusions from evidence, and in many cases also an algorithm to
learn aspects of the model from data. These can be challenging tasks,
making probabilistic reasoning require significant effort and expertise.
Furthermore, most probabilistic reasoning tools are standalone and
difficult to integrate into larger programs.

Figaro is a probabilistic programming language that helps address both
these issues. Figaro makes it possible to express probabilistic models
using the power of programming languages, giving the modeler the
expressive tools to create all sorts of models. Figaro comes with a
number of built-in reasoning algorithms that can be applied
automatically to new models. In addition, Figaro models are data
structures in the Scala programming language, which is interoperable
with Java, and can be constructed, manipulated, and used directly within
any Scala or Java program.

Figaro is extremely expressive. It can represent a wide variety of
models, including:

\begin{itemize}
\item
  directed and undirected models
\item
  models in which conditions and constraints are expressed by arbitrary
  Scala functions
\item
  models involving inter-related objects
\item
  open universe models in which we don't know what or how many objects
  exist
\item
  models involving discrete and continuous elements
\item
  models in which the elements are rich data structures such as trees
\item
  models with structured decisions
\item
  models with unknown parameters
\end{itemize}

Figaro provides a rich library of constructs to build these models, and
provides ways to extend this library to create your own model elements.

Figaro's library of reasoning algorithms is also extensible. Current
built-in algorithms include:

\begin{itemize}
\item
  Exact inference using variable elimination
\item
  Belief propagation
\item
  Lazy factored inference for infinite models
\item
  Importance sampling
\item
  Metropolis-Hastings, with an expressive language to define proposal
  distributions
\item
  Support computation
\item
  Most probable explanation (MPE) using variable elimination or
  simulated annealing
\item
  Probability of evidence using importance sampling
\item
  Particle Filtering
\item
  Factored frontier
\item
  Parameter learning using expectation maximization
\end{itemize}

Figaro provides both regular (the algorithm is run once) and anytime
(the algorithm is run until stopped) versions of some of these
algorithms. In addition to the built-in algorithms, Figaro provides a
number of tools for creating your own reasoning algorithms.

Figaro is free and is released under an open-source license (see license
file). The public code repository for Figaro can also be found at
\url{https://github.com/p2t2}

\subsection{What's New in Figaro 3.0?}\label{whats-new-in-figaro-3.0}

Many new features have been introduced into Figaro 3.0 since Figaro 2.0
was released. These include:

\begin{itemize}
\item
  A collections library. This library includes support for processes
  defined over an infinite space, such as Gaussian processes or
  continuous-time Markov processes. It also supports collections
  consisting of an unknown number of elements. Many convenient methods
  are defined on Figaro collections, including mapping values of
  elements in a collection through a function and folds or aggregates
  (for finite collections).
\item
  A number of new algorithms:

  \begin{itemize}
  \item
    Lazy variable elimination allows variable elimination to be used on
    very large or infinite models by only expanding part of the model
    and quantifying the contribution of the unexpanded part of the model
    on the query.
  \item
    Belief propagation for approximate factored inference.
  \item
    The factored frontier algorithm for filtering.
  \item
    A wider variety of expectation-maximization-based learning
    algorithms.
  \end{itemize}
\item
  Improvements to existing algorithms:

  \begin{itemize}
  \item
    Forward sampling algorithms like importance sampling and particle
    filtering now work in log space to avoid underflow.
  \item
    Importance sampling now properly implements likelihood weighting to
    avoid too many rejections.
  \item
    More algorithms support computing probability of evidence, including
    variable elimination, importance sampling, and particle filtering.
  \item
    Observations on continuous elements are now implemented as
    constraints on the arguments of the elements, which helps avoiding
    rejections and mixing.
  \item
    Ability to sample particular target variables without sampling all
    the variables.
  \end{itemize}
\item
  Features to make programming easier:

  \begin{itemize}
  \item
    New patterns for learning. Parameter collections enable you to reuse
    the same parameters in both the training model and operational
    model.
  \item
    One line shortcuts for common queries.
  \item
    Ability to query the mean and variance of a Double element.
  \item
    Ability to add logarithmic constraints to elements.
  \end{itemize}
\item
  New element classes in the library:

  \begin{itemize}
  \item
    Multivariate normal
  \item
    Inverse gamma
  \item
    Parameterized binomial
  \item
    Fold for implementing associative aggregates efficiently
  \end{itemize}
\item
  Numerous minor improvements and bug fixes
\end{itemize}

\subsection{Where can I get Figaro binary
distributions?}\label{where-can-i-get-figaro-binary-distributions}

The latest stable Figaro binary release is available for download from
the Charles River Analytics, Inc. Web site:

\url{http://www.cra.com/figaro}

Each binary release comes with Figaro, all required libraries, Scaladoc,
examples, and source code.

\subsection{How do I run the Figaro
Examples?}\label{how-do-i-run-the-figaro-examples}

The easiest way to run the Figaro examples is to install Scala and use
the latest Figaro binary release.

To get started, download Scala from
\url{http://scala-lang.org/download/}. You will need Scala version
2.11.2 or later to run the latest Figaro release. Follow the Scala
installation instructions at
\url{http://scala-lang.org/download/install.html} and make sure you can
run, compile, and execute the ``Hello World'' program provided in the
documentation.

The next step is to obtain Figaro. The Figaro binary distribution is
hosted at the Charles River Analytics, Inc. Web site at
www.cra.com/figaro. The current version, as of January 2015, is 3.0.0.0
and is available for Scala 2.11. Make sure the Figaro version you use
matches the Scala version. Each available download link is a compressed
archive containing the Figaro jar (jar is the Java/Scala format for
compiled byte code), examples, documentation, Scaladoc, and source code
files. Click the appropriate link and then uncompress the downloaded
archive to access the files. In each distribution, you will find a
Figaro jar with a name ending with ``fat'' (such as
``figaro\_2.11-3.0.0.0-fat.jar''), indicating that this is a fat jar
containing all the necessary libraries to run Figaro.

The final step is to open a command prompt and switch to the
uncompressed Figaro download directory. Using the Scala command line
program, run any Figaro example by setting the Scala classpath and
invoking the desired class:

scala -cp figaro\_2.11-3.0.0.0-fat.jar;figaroexamples\_2.11-3.0.0.0.jar
\textless{}example\_class\textgreater{}

For example, to run the Burglary program:

scala -cp figaro\_2.11-3.0.0.0-fat.jar;figaroexamples\_2.11-3.0.0.0.jar
com.cra.figaro.example.Burglary

\subsection{What Figaro Example classes are
available?}\label{what-figaro-example-classes-are-available}

The following examples are available in the Figaro Examples JAR file
included in the binary release:

com.cra.figaro.example.AnnealingSmokers

com.cra.figaro.example.Burglary

com.cra.figaro.example.CarAndEngine

com.cra.figaro.example.CoinExample

com.cra.figaro.example.DiceExample

com.cra.figaro.example.Entrepreneur

com.cra.figaro.example.Firms

com.cra.figaro.example.Hierarchy

com.cra.figaro.example.LazyList

com.cra.figaro.example.MultiDecision

com.cra.figaro.example.MultiValuedReferenceUncertainty

com.cra.figaro.example.MutableMovie

com.cra.figaro.example.OpenUniverse

com.cra.figaro.example.OpenUniverseLearning

com.cra.figaro.example.SimpleLearning

com.cra.figaro.example.SimpleMovie

com.cra.figaro.example.Smokers

com.cra.figaro.example.Sources

com.cra.figaro.example.dosage.DosageDecision

com.cra.figaro.example.graph.GraphDecision

\subsection{How do I run my own Figaro
programs?}\label{how-do-i-run-my-own-figaro-programs}

The simplest way to compile and run the Figaro programs you create is to
use the Simple Build Tool (SBT) program and the FigaroWork project.

FigaroWork is an SBT project that enables users to quickly start writing
their own Figaro programs. The project is set up to automatically pull
in the relevant versions of Scala and Figaro, so there is nothing else
for you to install. SBT also makes sure the Scala classpath is
configured correctly for your project, saving you some hassle when
running your programs.

To get started, download and uncompress the FigaroWork files to a
directory on your machine. The FigaroWork project is hosted at the
Charles River Analytics, Inc. Web site at
\url{https://www.cra.com/figaro}. Then download the latest release of
SBT v0.13 for your operating system at
\url{http://www.scala-sbt.org/download.html} and install it following
these guidelines
\url{http://www.scala-sbt.org/0.13/tutorial/Manual-Installation.html}.

When you have finished installing, you will have the following
directories and files on your machine:

\textbackslash{}FigaroWork

README.txt

\textbackslash{}project

build.properties

Build.scala

plugins.sbt

\textbackslash{}src

\textbackslash{}main

\textbackslash{}scala

Test.scala

Test your new build environment by running the simple Figaro test
program provided with the project. Open a command prompt, navigate to
your local FigaroWork directory (ex. C:\textbackslash{}FigaroWork), and
run this command

sbt "runMain Test"

This command tells SBT to compile the Scala files in the project and
execute the main() method of the Test class. Remember to include the
quotes around the runMain command. You should see output similar to this

{[}info{]} Running Test

1.0

Now you can copy your existing Figaro program packages and Scala source
files to

\textbackslash{}FigaroWork\textbackslash{}src\textbackslash{}main\textbackslash{}scala

or create new ones there. Run your Figaro program like this

sbt "runMain \textless{}class\_with\_main\textgreater{}
\textless{}parameters\textgreater{}"

Replace \textless{}class\_with\_main\textgreater{} with the package and
class that contains the main() method that starts your Figaro program.
Replace \textless{}parameters\textgreater{} with the list of command
line parameters (if any) your program may need to run. For example

sbt "runMain com.cra.test.FigaroTest parameter1 parameter2 parameter3"

\subsection{How do I run my own Figaro programs without
SBT?}\label{how-do-i-run-my-own-figaro-programs-without-sbt}

While SBT is a useful tool, you may want to manage your own workspace
differently.

To run Figaro, you will first need Scala. The Scala compiler can either
be run from the command line or within an Integrated Development
Environment (IDE). Two IDEs that support Scala development are Eclipse
and IntelliJ Idea. NetBeans also has a Scala plugin but it does not
appear to support recent versions of Scala (but that may have changed).
This section focuses on how to obtain Scala and Figaro and run Scala
programs that use Figaro from the command line. If you choose to use an
IDE, please see the documentation of your IDEs and Scala plugins for
details of how to include the Figaro library.

To get started, download Scala from
\url{http://scala-lang.org/download/}. You will need Scala version
2.11.2 or later to run the latest version of Figaro. Follow the Scala
installation instructions at
\url{http://scala-lang.org/download/install.html} and make sure you can
run, compile, and execute the ``Hello World'' program provided in the
documentation.

The next step is to obtain Figaro. The Figaro binary distribution is
hosted at the Charles River Analytics, Inc. Web site. Go to
www.cra.com/figaro. The current version, as of January 2015, is 3.0.0.0,
and is available for Scala 2.11. Always make sure the Figaro version you
use matches the Scala version you're using. Each available download link
is a compressed archive containing the Figaro jar (jar is the Java/Scala
format for compiled byte code), examples, documentation, Scaladoc, and
source code files. Click the appropriate link and then uncompress the
downloaded archive to access the Figaro jar file. In the distribution,
the Figaro jar name ends with ``fat'', indicating that this is a fat jar
containing all the necessary libraries to run Figaro. Using a fat jar
simplifies the Scala classpath needed to run Figaro programs.

Optionally, you can add the fully qualified path name of the Figaro jar
to your classpath. This can be done by adding the Figaro jar to the
CLASSPATH environment variable in your operating system. The process for
editing the CLASSPATH varies from operating system to operating system.
You can see details about using the PATH and CLASSPATH environment
variables in
\url{http://docs.oracle.com/javase/tutorial/essential/environment/paths.html}.

If the CLASSPATH does not exist yet, create it. It is good practice to
include the current working directory, so set the CLASSPATH to ``.'',
then proceed to add the Figaro jar, as in the next step.

By this point, the CLASSPATH already exists, so we can add the Figaro
path to it. For example, on Windows 7, if figaro\_2.11-3.0.0.0-fat.jar
is in the ``C:\textbackslash{}Users\textbackslash{}apfeffer'' folder and
the CLASSPATH is currently equal to ``.'', change the CLASSPATH to
``C:\textbackslash{}Users\textbackslash{}apfeffer\textbackslash{}figaro\_2.11-3.0.0.0-fat.jar;.''
(replace 3.0.0.0 with the appropriate Figaro version number).

Now you can compile and run Figaro programs just like any Scala program.
Put the Test program below in a file named Test.scala. First, let's
assume you followed step 4 and updated the CLASSPATH.

If you run scala Test.scala from the directory containing Test.scala,
the Scala compiler will first compile the program and then execute it.
It should produce the output 1.0.

If you run scalac Test.scala (note the c at the end of ``scalac''), the
Scala compiler runs and produces .class files. You can then execute the
program by running scala Test from the same directory.

If you did not follow step 4, you can set the CLASSPATH from the command
line using the --cp option. For example, to compile and execute
Test.scala, assuming figaro\_2.11-3.0.0.0-fat.jar is in the
``C:\textbackslash{}Users\textbackslash{}apfeffer'' folder, you can run

scala --cp
C:\textbackslash{}Users\textbackslash{}apfeffer\textbackslash{}figaro\_2.11-3.0.0.0-fat.jar
Test.scala

Here's the Test program:

\begin{quote}
import com.cra.figaro.language.\_

import com.cra.figaro.algorithm.sampling.\_

object Test \{

def main(args: Array{[}String{]}) \{

val test = Constant("Test")

val algorithm = Importance(1000, test)

algorithm.start()

println(algorithm.probability(test, "Test"))

\}

\}
\end{quote}

This program should output 1.0 when run.

\subsection{How do I compile Figaro from source
code?}\label{how-do-i-compile-figaro-from-source-code}

Figaro is maintained as open source on GitHub. The GitHub project is
Probabilistic Programming Tools and Techniques (P2T2), located at
\url{https://github.com/p2t2}. P2T2 currently contains the Figaro
sources, but we plan to update it with more tools. If you want to see
the source code and build Figaro yourself, please visit our GitHub site.

To build Figaro from GitHub source, make a fork of the Figaro repository
to your GitHub account, then use git's clone feature to get the source
code from your GitHub account to your machine.

git clone https://github.com/{[}your-github-username{]}/figaro.git

There are several branches available; checkout ``master'' for the latest
stable release or the latest ``DEV'' branch for more cutting edge work
and features (this is work in progress and therefore less stable).

Figaro uses Simple Build Tool (SBT) to manage builds, located at
\url{http://www.scala-sbt.org/}. Download and install SBT, open a
command prompt, switch to your newly cloned local Figaro directory, and
enter this SBT command set:

sbt clean compile package publishLocal assembly copy-deps

This will create Figaro for Scala 2.11; you will find the resulting
artifacts in the ``target'' directory.

To run the Figaro unit tests, use this SBT command

sbt test

Note that some of the unit tests may not always pass because their
results are non-deterministic.

\subsection{How can I use Figaro in my
project?}\label{how-can-i-use-figaro-in-my-project}

If you wish to integrate Figaro's features into your own software
project, Figaro is available on Maven Central
(\url{http://search.maven.org}). Shown below are a few examples of how
you can add Figaro as a dependency to your existing project:

\emph{Simple Build Tool (SBT) Projects}

libraryDependencies += "com.cra.figaro" \%\% "figaro" \% "3.0.0.0"

\emph{Apache Maven Projects}

\begin{quote}
\textless{}dependency\textgreater{}

~~~~\textless{}groupId\textgreater{}com.cra.figaro\textless{}/groupId\textgreater{}

~~~~\textless{}artifactId\textgreater{}figaro\_2.11\textless{}/artifactId\textgreater{}

~~~~\textless{}version\textgreater{}3.0.0.0\textless{}/version\textgreater{}

\textless{}/dependency\textgreater{}
\end{quote}

\emph{Apache Ivy Projects}

\textless{}dependency org="com.cra.figaro" name="figaro\_2.11"
rev="3.0.0.0" /\textgreater{}

\end{document}
